#ifndef _MMC_H_
#define _MMC_H_
#include "gd32f30x.h"
#include <stdio.h>
#include <stdbool.h>
#include <string.h>
#include "FreeRTOS.h"
#include "task.h"
#include "semphr.h"	

typedef struct {
    SemaphoreHandle_t sem_req;
    SemaphoreHandle_t sem_ack;
    void* p_shared_mem;
    int shared_mem_nbyte;
} mmc_ctrl_t;


/**
 * @desc  : 初始化MMC控制器（创建同步信号量、初始化共享内存）
 * @date  : 2025-11-04
 * @author: AnRui
 * @param : p_mmc_ctrl - MMC控制结构体指针（需提前分配内存，非NULL）
 * @param : p_sm - 共享内存缓冲区指针（用于任务间数据传递的内存地址）
 * @param : sm_len - 共享内存缓冲区长度（单位：字节，需大于0）
 * @param : sm_name - 共享内存名称（用于日志打印，标识该共享内存用途）
 * @note  : 1. 必须在使用MMC控制器前调用，完成信号量和共享内存的初始化；
 *          2. 创建两个二值信号量：sem_req（请求信号量，用于发送处理请求）、sem_ack（应答信号量，用于接收处理完成通知）；
 *          3. 共享内存会被初始化为全0，确保初始状态无垃圾数据。
 */
void mmc_ctrl_init(mmc_ctrl_t* p_mmc_ctrl, void* p_sm, int sm_len);


/**
 * @desc  : 发送请求信号 + 阻塞等待应答（请求-应答同步核心接口）
 * @date  : 2025-11-04
 * @author: AnRui
 * @param : req_sema - 请求信号量（用于通知接收方“有数据待处理”）
 * @param : ack_sema - 应答信号量（用于等待接收方“处理完成”的通知）
 * @param : timeout - 等待应答的超时时间（单位：FreeRTOS系统节拍，portMAX_DELAY表示无限等待）
 * @return: bool - 执行结果（true：请求发送成功且收到应答；false：信号量无效/发送失败/超时未收到应答）
 * @note  : 1. 调用前需确保接收方已在等待req_sema（否则可能出现信号量丢失）；
 *          2. 数据传递需通过外部共享内存完成（本函数仅负责同步，不处理数据）；
 *          3. 典型流程：发送方写入数据到共享内存 → 调用本函数发送请求 → 接收方获取req_sema后处理数据 → 接收方释放ack_sema → 发送方被唤醒继续执行。
 */
bool mmc_send_req_and_wait_ack(SemaphoreHandle_t req_sema, SemaphoreHandle_t ack_sema, int timeout);



/**
 * @desc  : 通过MMC控制器发送请求并等待应答
 * @date  : 2025-11-04
 * @author: AnRui
 * @param : p_mmc_ctrl - MMC控制结构体指针
 * @param : wait_time - 等待应答的超时时间
 * @return: bool - 执行结果（true：请求发送成功且收到应答；false：失败，原因包括控制结构体无效/信号量操作失败/超时）
 * @note  : 1. 调用前需先向p_mmc_ctrl->p_shared_mem写入待传递的数据（本函数不处理数据写入）；
 *          2. 内部直接调用mmc_send_req_and_wait_ack，复用同步逻辑，简化外部调用；
 *          3. 原代码存在笔误：参数timeout未定义，应改为wait_time（需修正，否则编译报错）。
 */
bool mmc_ctrl_require(mmc_ctrl_t* p_mmc_ctrl, int wait_time);




#endif
